COMMENT ⊗   VALID 00013 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002			General PUB Macros in GENRAL.PUB[SUB,SYS]
C00005 00003			Output Device
C00006 00004			Fonts and Special Characters
C00012 00005			Sides of the Page to Be Printed
C00014 00006			Slurping Up the Macros File
C00015 00007			Columns per Side to Be Printed
C00016 00008			Spacing
C00017 00009			Section Headings
C00021 00010			Text Justification
C00023 00011			Footnotes
C00025 00012			Automatic Generation of Table of Contents
C00026 00013			Example
C00028 ENDMK
C⊗;
		General PUB Macros in GENRAL.PUB[SUB,SYS]
			Version 1.1, 4 March 1976
			     Brian P. McCune

GENRAL.PUB[SUB,SYS] sets  up  some standardized  PUB conventions  for
producing  documents.   These macros are  designed for  two different
user groups.  The  first consists of casual  PUB users who desire  to
avoid having to learn much about PUB.  The price you pay for being in
this  group is that you  have to live with  the features and document
formats that are provided.  The second group is  that of PUB hackers.
By copying these macros to your own disk area, these macros provide a
starting place for the venturesome souls  who want to tailor them  to
their own needs.

The features provided  by these macros  include use of either  XGP or
LPT  as output  device; lightface,  italic, and  boldface Baskerville
fonts with  all  keyboard  characters of  Stanford  ASCII  available;
formats for printing  on either one or both sides  of a page; formats
for printing  one or two columns per side; single, double, triple, or
even greater  spacing; macros  for four levels  of section  headings;
footnote generation;  and automatic generation of  table of contents.
Follow the instructions below  to properly set up  your .PUB file  to
get the desired options.

See "PUB:  The Document  Compiler" (in  PUB.TES[S,DOC]) and the  "PUB
Update" (in PUB.UPD[S,DOC]) for the details of PUB.
		Output Device

Using the appropriate command of

	.DEVICE XGP;
	.DEVICE LPT;

choose  the  desired  output device.    XGP  is  highly  recommended;
however, note that LPT is useful if you want a document which is both
printable and readable online and  one which can be printed at  sites
not possessing an XGP.
		Fonts and Special Characters

The following paragraph is in effect only if  the device type is XGP.
Font  1  is  defined to  be  lightface  Baskerville;  Font 2,  italic
Baskerville; Font  3, boldface  Baskerville; Font  4,  FIX25 for  the
special characters not available in  Baskerville; and Font 5, SUP for
footnote numbers.  You are started out in lightface Baskerville.  All
of the Baskerville ligatures are provided automatically.   All of the
Baskerville  fonts  provide  access  to  all of  the  Stanford  ASCII
characters which can  be typed  in from  a Stanford  keyboard.   (The
characters "hidden" beneath  NULL, TAB, LF,  VT, FF, CR, ALT,  and BS
are  unavailable.) Note that  logical not  ("¬") will print  as such;
type two consecutive hyphens ("--") to  get a dash.  Alpha ("α")  and
percent  sign ("%")  are  turned  on as  PUB  response characters  to
provide  for  quoting  characters and  changing  fonts, respectively.
Please do  not turn off  alpha; if you  need an  alpha in your  text,
quote it ("αα").  Surrounding  a section of text with the appropriate
delimiters will cause it to be printed in //italics/ or  ⊗⊗boldface⊗.
Note that you can't  get an italic slash or boldface  circle times if
you  use this  scheme; switch  fonts by  using percent  sign instead.
Also, a double quote in  italics or boldface must be doubled  (`""').
After the special font is over, you are returned to the font that you
were in  upon entry.  Thus, you can switch to italic or boldface from
any different font.   But, please,  no recursion!   A pair of  double
quotes is  converted into a pair of  matching Baskerville open double
quote and close double quote.   If you want exactly one double  quote
(e.g., as an abbreviation for inches), you must type `α"'.  Note that
nested  pairs of double quotes  won't work; use single  quotes on the
second level  and  don't go  any deeper  than  that.   The  following
characters should be input as shown:

	to get						input
	α						αα
	%						α%
	" (unmatched)					α"
	dash						--
	//						/α/
	⊗⊗						⊗α⊗
	circumflex (lightface only)			αε
	period with extra space (lightface only)	α∀
	" (italic and boldface only)			""
	" (unmatched, italic and boldface only)		α""

The following paragraph is in  effect only if the device is  LPT.  If
the device type is LPT, too bad!  You only get LPT font for starters.
Alpha ("α") and the underline command characters ("↓_" and  "_↓") are
turned on.   The font switching character ("%") is  turned on so that
if  you have font switches in a  document that was originally done on
the XGP, they  will act as  no-ops and be  swallowed up.  Instead  of
italic type, you  get things //underlined/.  Note  that you can't get
an underlined  slash  using  this scheme;  use  ↓_text  with  slash_↓
instead.  Instead of  boldface, you get ⊗⊗all capital  letters⊗.  You
can't get an underbar or circle times within all capitals however, so
exit all capitals  mode for one  character instead.   Also, a  double
quote in underline  or all capitals mode must be  doubled.  Underline
and  all  capitals modes  even  work simultaneously.    The following
characters should be input as shown:

	to get						input
	α						αα
	%						α%
	↓						α↓
	//						/α/
	⊗⊗						⊗α⊗
	" (underline and all capitals only)		""
		Sides of the Page to Be Printed

Using the appropriate statement of

	.SIDES ← 1;
	.SIDES ← 2;

choose whether printing will be on one side of  a page or both sides.
For documents that will be printed on only one side of the paper, the
section name of the current section will appear in the upper  left of
each  page and  the current  page  number in  the upper  right.   For
documents  that will  be  printed on  both sides  of the  paper, even
numbered (lefthand) pages will have the page number in the upper left
corner  and  the section  name  in the  upper  right.   Odd  numbered
(righthand) pages will have the subsection name (if any) in the upper
left and  the page  number in  upper right.   All  page headings  are
printed in boldface Baskerville (but not in all capitals on LPT).
		Slurping Up the Macros File

Following the  DEVICE and SIDES  statements (discussed  above), there
must be a statement of the form

	.REQUIRE "GENRAL.PUB[SUB,SYS]" SOURCE_FILE;

All  macro  calls  discussed below  must  occur  after  this  REQUIRE
statement.
		Columns per Side to Be Printed

By using the appropriate command of

	.COLMNS 1;
	.COLMNS 2;

printing will be  done in either one column  or two.  In  either case
the top, bottom, left,  and right margins are all one inch.  With two
columns there  is a  one-half inch  space between  the  columns.   In
addition, in  the middle of  your text you can  switch to one  or two
column printing  by using the appropriate command; however, this will
start a new page.  If there is a table of contents, it will be in the
column format specified by the last COLMNS command given.
		Spacing

By using the command

	.SPACES <positive integer>;

you will  get single, double,  triple, etc.   spacing (i.e.,  1 gives
single  spacing, 2  double spacing,  etc.).   Spacing can  be changed
throughout a document,  but such a change  causes a paragraph  break.
Initially  single  spacing is  assumed.    If  there  is a  table  of
contents,  it will  be spaced  according to  the last  SPACES command
given.
		Section Headings

Main sections and appendices can either start a new page (an odd page
if printing two sides) by using

	.NEW_PAGE_ON_SECTION TRUE;

or not start a new page by using

	.NEW_PAGE_ON_SECTION FALSE;

If the latter  mode is in  effect, then at  least five lines  of text
will follow the  section heading in the same column.  Initially a new
section will start a new page.

Begin each logical segment of your document  with the appropriate one
of the following macros:

	.S |<section name>|;
	.SS |<subsection name>|;
	.SSS |<subsubsection name>|;
	.APP |<appendix name>|;

None of these section names should contain a vertical bar ("|"), left
curly  bracket  ("{"),  left  arrow  ("←"),  or  right  arrow  ("→").
Sections will  be numbered one  up.   Subsections and  subsubsections
will  be  numbered decimally  within  the  section.   Appendices  are
labelled with capital letters, beginning with "A".  All three section
levels, as well as appendices,  will appear in the table  of contents
if there is one (see  below).  All section and appendix headings will
appear in boldface Baskerville (all capitals for LPT).  At least four
lines of text will occur below a subsection  name in the same column;
at least three lines are guaranteed for subsubsections.

If you wish  to have an unnumbered  section which will not  appear in
the  table of  contents, use  the following macro  to make  its title
appear centered and in boldface Baskerville (all capitals for LPT):

	.CB |<title>|;

The same conventions  as for section names  hold for this title.   CB
guarantees that  at least two lines of text  occur below the title in
the same column.

None of the line  guarantees specified in this section  are in effect
within  a column containing  footnotes.  If  you end up  with a widow
section heading, put a GROUP  command just before the heading and  an
APART command just after the first paragraph following the heading.
		Text Justification

Another handy macro is

	.JUSTIFY;

which begins standard text justification.   Just before entering your
text file JUSTIFY is  called, so you will only need to call it if you
ever stop justifying for some reason.

Note that  this macro RETAINs  all blanks between  words in  order to
allow for  two blanks after sentences ending  with a period, question
mark, exclamation  mark,  colon, right  parenthesis,  right  bracket,
right single  quote, double quote,  etc.  In  order for this  to work
correctly, you  must always leave the exact number of blanks that you
want to appear in the justified text.  Unwanted  blanks (often caused
by fixed width justification such as exhibited in this paragraph) can
be removed by using the ETV extended command JFILL.
		Footnotes

A footnote that will  appear at the bottom of the  current column can
be generated  at the point of  reference.  This is done  by a call of
the form

	∪∪<text of footnote>∪

Because  of this  format, you  can't  use a  "∪"  character inside  a
footnote.

Footnotes are numbered  one up within  each main section.   The above
call is replaced  by the next footnote number generated, displayed as
a superscript numeral (a numeral in brackets on LPT).   The footnotes
for a column  will appear sequentially at the bottom  of that column,
separated  from the  main text  by a  solid line  of underbars.   The
footnote entry consists of  the footnote number followed by  the text
of the footnote.   The text is displayed  single spaced, in lightface
Baskerville font, and justified.

Caution: The handling  of footnotes by PUB  is known to be  buggy, so
be prepared to fiddle a bit to get them to work.
		Automatic Generation of Table of Contents

If you wish to have a table of contents, put the PUB statement

	.INSERT CONTENTS;

before the REQUIRE statement discussed above and call the macro

	.COLLECT CONTENTS;

at the very  end of your document.   Note that the column  format and
spacing of  the table of contents are determined  by the last call to
COLMNS  and   SPACES,  respectively.     Currently   calling   COLMNS
immediately before COLLECT  CONTENTS doesn't work quite  right, so be
sure to have some text in between.
		Example

Here is an example of using these commands.  The text of the paper in
this case  is located in TEST.TXT.  A  two sided, two column document
will be produced for the XGP.   Using the optional commands in  curly
brackets will override  the default conditions, producing  a table of
contents,  a double spaced document, and no  new page at the start of
main sections and appendices.

	.DEVICE XGP;
	.SIDES ← 2;
       {.INSERT CONTENTS;}
	.REQUIRE "GENRAL.PUB[SUB,SYS]" SOURCE_FILE;
	.COLMNS 2;
       {.SPACES 2;}
       {.NEW_PAGE_ON_SECTION FALSE;}
	.REQUIRE "TEST.TXT" SOURCE_FILE;
       {.COLLECT CONTENTS;}

If the file containing the above statements  is called TEST.PUB, then
you should call PUB with the monitor command

	.PUB TEST